<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<link rel="shortcut icon" type="image/x-icon" href="favicon.ico"/>
<title>DynamoRIO API: Client Transparency</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">DynamoRIO API
   </div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.1.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('transparency.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Client Transparency </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>DynamoRIO must avoid interfering with the semantics of a program while it executes. Shifting execution from the original application code into a cache that occupies the application's own address space provides flexibility but complicates transparency. To achieve transparency, DynamoRIO cannot make any assumptions about a program's stack usage, heap usage, or any of its dependencies on the instruction set architecture or operating system. DynamoRIO's transparency restrictions necessarily apply to a client aswell. Contents:</p>
<ul>
<li><a class="el" href="transparency.html#sec_trans_resource">Resource Usage Conflicts</a></li>
<li><a class="el" href="transparency.html#sec_trans_unmod">Leaving the Application Unchanged When Possible</a></li>
<li><a class="el" href="transparency.html#sec_trans_pretend">Pretending The Application Is Unchanged When It Is Not</a></li>
<li><a class="el" href="transparency.html#sec_trans_alertable">Alertable System Calls</a></li>
</ul>
<p>We first describe each of the three transparency categories for DynamoRIO and their ramifications for clients using the code cache.</p>
<h1><a class="anchor" id="sec_trans_resource"></a>
Resource Usage Conflicts</h1>
<p>Ideally, DynamoRIO and its client's resources should be completely disjoint from the application's, to avoid conflicts in the usage of libraries, heap, input/output, and locks. Library conflicts are the most relevant to a client.</p>
<dl class="section user"><dt>Library Transparency</dt><dd></dd></dl>
<p>Sharing libraries with the application can cause problems with re-entrancy and corruption of persistent state like error codes. DynamoRIO's dispatch code can execute at arbitrary points in the middle of application code; a client's instrumentation is similarly executed. If both the application and DynamoRIO use the same non-re-entrant library routine, DynamoRIO might call the routine while the application is inside it, causing incorrect behavior. We have learned this lesson the hard way, having run into it several times. The solution is for DynamoRIO's external resources to come only from system calls and never from user libraries. This is straightforward to accomplish on Linux, and most operating systems, where the system call interface is a standard mechanism for requesting services (<em>a</em> in the figure below). However, on Windows, the documented method of interacting with the operating system is not via system calls but instead through an application programming interface (the {<em>Win32</em> API}) built with user libraries on top of the system call interface (<em>b</em> in the figure). If DynamoRIO uses this interface, re-entrancy and other resource usage conflicts can, and will, occur. To achieve full transparency on Windows, the system call interface (<em>c</em> in the figure) must be used, rather than the API layer.</p>
<div class="image">
<img src="windows.png" alt="windows.png"/>
</div>
  <p>DynamoRIO provides access to resources to clients via a cross-platform API. We do not recommend that a client invoke its own system calls as this bypasses DynamoRIO's monitoring of changes to the process address space and changes to threads or control flow.</p>
<p>We provide limited support to assist in using statically linked libraries in a client: see <a class="el" href="using.html#sec_extlibs">Using External Libraries</a>.</p>
<p>In addition to Library Transparency, several other types of transparency are of concern to a client:</p>
<dl class="section user"><dt>Heap Transparency</dt><dd></dd></dl>
<p>Sharing heap allocation routines with the application violates Library Transparency. Most heap allocation routines are not re-entrant (they are thread-safe, but not re-entrant). Additionally, DynamoRIO should not interfere with the data layout of the application (Data Transparency: see below) or with application memory bugs (Error Transparency: see below). DynamoRIO obtains its memory directly from system calls and parcels it out internally with a custom memory manager. It exports its heap allocation routines through its API to ensure that clients maintain Heap Transparency (see <a class="el" href="using.html#sec_utils">Common Utilities</a>).</p>
<dl class="section user"><dt>Input/Output Transparency</dt><dd></dd></dl>
<p>DynamoRIO uses its own input/output routines to avoid interfering with the application's buffering. As with heap transparency, DynamoRIO exports its input/output routines to clients to ensure that transparency is not violated (see <a class="el" href="using.html#sec_utils">Common Utilities</a>).</p>
<dl class="section user"><dt>Synchronization Transparency</dt><dd></dd></dl>
<p>DynamoRIO and its clients must avoid acquiring locks that the application also acquires, such as the <code>LoaderLock</code> on Windows. Additionally, there are restrictions imposed by DynamoRIO on when its own locks can be acquired, to allow it to safely synchronize with multiple threads:</p>
<h1><a class="anchor" id="sec_trans_unmod"></a>
Leaving the Application Unchanged When Possible</h1>
<p>As many aspects of the application as possible should be left unchanged:</p>
<p><a class="anchor" id="sec_trans_floating_point"></a></p>
<dl class="section user"><dt>Floating Point State, MMX, and SSE Transparency</dt><dd></dd></dl>
<p>Because it is expensive to do so and rarely necessary, DynamoRIO does <em>NOT</em> save or restore the floating point state or MMX (64-bit) registers during a context switch away from the application. If at any time a client wishes to use floating point or multimedia operations, it must explicitly preserve the state. The <a class="el" href="dr__ir__utils_8h.html#ae7b7bd1e750b8a24ebf401fb6a6d6d5e">dr_insert_clean_call()</a> routine takes a boolean indicating whether floating point state should be preserved across the call; this is the most convenient method for saving the state.</p>
<p>The state can alternatively be saved explicitly from C code using:</p>
<div class="fragment"><div class="line"><a class="code" href="dr__proc_8h.html#a4a11c9d5d127ce126562ad35b4d165dd">proc_save_fpstate</a>(byte *buf)</div>
<div class="line"><a class="code" href="dr__proc_8h.html#a23edceee5d1ae7c7d51a212432e6d644">proc_restore_fpstate</a>(byte *buf)</div>
</div><!-- fragment --><p>Saving can be done from inlined code in the code cache using:</p>
<div class="fragment"><div class="line"> <a class="code" href="dr__proc_8h.html#aac57f229cefee3abdc6a45dfa37557f6">dr_insert_save_fpstate</a>(), <a class="code" href="dr__proc_8h.html#ae2f93e0bd2ccdd9e1fe15752198e6c57">dr_insert_restore_fpstate</a>() </div>
</div><!-- fragment --><p>These routines require a buffer that is 16-byte-aligned and of a certain size (512 bytes for processors with the FXSR feature, and 108 bytes for those without). Here is a sample usage:</p>
<div class="fragment"><div class="line">byte fp_raw[512 + 16];</div>
<div class="line">byte *fp_align = (byte *) ( (((ptr_uint_t)fp_raw) + 16) &amp; ((ptr_uint_t)-16) );</div>
<div class="line"><a class="code" href="dr__proc_8h.html#a4a11c9d5d127ce126562ad35b4d165dd">proc_save_fpstate</a>(fp_align);</div>
</div><!-- fragment --><p>Note that floating point operations include almost any operation that acts on a float, even printing one with %f.</p>
<p>The XMM (128-bit) registers are saved by DynamoRIO on context switches and clean calls only for a 64-bit Windows kernel (whether in a 32-bit process (WOW64) or a 64-bit process) or for 32-bit and 64-bit Linux applications. For a 64-bit Windows kernel, xmm0 through xmm5 are preserved; for a 64-bit Linux application, xmm0 through xmm15 are preserved; for a 32-bit Linux application, xmm0 through xmm7 are preserved. For all other platforms, it is up to the client to preserve the xmm registers, and for 64-bit Windows kernels, to preserve the rest of the xmm registers beyond xmm5, if any code is invoked that modifies them. See also the <a class="el" href="dr__ir__utils_8h.html#a5921c4f301ea05885f305f9a30b3c0b0">dr_mcontext_xmm_fields_valid()</a> routine.</p>
<p><a class="anchor" id="sec_trans_thread"></a></p>
<dl class="section user"><dt>Thread Transparency</dt><dd></dd></dl>
<p>For full transparency, if DynamoRIO or a client creates extra threads they should be hidden from any introspection performed by the application.</p>
<dl class="section user"><dt>Executable Transparency</dt><dd></dd></dl>
<p>The program binary and shared library files on disk should not be modified.</p>
<dl class="section user"><dt>Data Transparency</dt><dd></dd></dl>
<p>DynamoRIO leaves application data unmodified, including heap layout.</p>
<dl class="section user"><dt>Stack Transparency</dt><dd></dd></dl>
<p>The application stack must look exactly like it does natively. It is tempting to use the application stack for scratch space, but we have seen applications like Microsoft Office access data beyond the top of the stack (i.e., the application stores data on the top of the stack, moves the stack pointer to the previous location, and then accesses the data). Using the application stack for scratch space would clobber such data. Additionally, hand-crafted code might use the stack pointer as a general-purpose register. Other and better options for temporary space are available. DynamoRIO provides thread-local storage through its API.</p>
<p>DynamoRIO provides a separate stack to use for itself and for the client, and never assumes even that the application stack is valid. Many applications examine their stack and may not work properly if something is slightly different than expected.</p>
<h1><a class="anchor" id="sec_trans_pretend"></a>
Pretending The Application Is Unchanged When It Is Not</h1>
<p>For changes that are necessary (such as executing out of a code cache), DynamoRIO must warp events like interrupts, signals, and exceptions such that they appear to have occurred natively.</p>
<dl class="section user"><dt>Cache Consistency</dt><dd></dd></dl>
<p>DynamoRIO must keep its cached copies of the application code consistent with the actual copy in memory. If the application unloads a shared library and loads a new one in its place, or modifies its own code, DynamoRIO must change its code cache to reflect those changes to avoid incorrectly executing stale code. If the client needs to modify application code, it should do so through the basic block event, rather than directly.</p>
<dl class="section user"><dt>Address Space Transparency</dt><dd></dd></dl>
<p>DynamoRIO must pretend that it is not perturbing the application's address space. An application bug that writes to invalid memory and generates an exception should do the same thing under DynamoRIO, even if we have allocated memory at that location that would natively have been invalid. This requires protecting all DynamoRIO memory from inadvertent (or malicious) writes by the application. Furthermore, DynamoRIO hides itself from introspection by manipulating memory queries.</p>
<dl class="section user"><dt>Application Address Transparency</dt><dd></dd></dl>
<p>Although the application's code is moved into a cache, every address manipulated by the application must remain an original application address. DynamoRIO must translate indirect branch targets from application addresses to code cache addresses, and conversely if a code cache address is ever exposed to the application, DynamoRIO must translate it back to its original application address. The latter occurs when the operating system hands a machine context to a signal or exception handler. In that case both the faulting or interrupted address and the complete register state must be made to look like the signal or exception occurred natively, rather than inside the code cache where it actually occurred.</p>
<p>To save space, DynamoRIO does not store any mappings from code cache state to application state. Since our cache consistency guarantees that the original application code cannot have changed since we built a fragment, we re-create the fragment from the original code, applying all the same transformations we applied when we first copied it into our code cache. We then walk through the reproduction and the code cache version in lockstep until we reach the target instruction. In order to accomplish this algorithm in code that has been modified or re-arranged by a client, DynamoRIO needs client support. We have not yet implemented this support. </p>
<dl class="section user"><dt>Error Transparency</dt><dd></dd></dl>
<p>Application errors under DynamoRIO must occur as they would natively. We accomplish this by maintaining Heap Transparency, Data Transparency, Stack Transparency, and Address Space Transparency, We have seen many cases of applications that access invalid memory natively, handle the exception, and carry on. Without Error Transparency such applications would not work properly under DynamoRIO.</p>
<dl class="section user"><dt>Timing Transparency</dt><dd></dd></dl>
<p>We would like to make it impossible for the application to determine whether it is executing inside of DynamoRIO. However, this may not be attainable for some aspects of execution, such as the exact timing of certain operations. This brings efficiency into the transparency equation.</p>
<p>Changing the timing of multi-threaded applications can uncover behavior that does not normally happen natively. We have encountered race conditions while executing under DynamoRIO that are difficult to reproduce outside of our system. These are not strictly speaking transparency violations, as the errors <em>could</em> have occurred without us, but are best avoided.</p>
<dl class="section user"><dt>Debugging Transparency</dt><dd></dd></dl>
<p>A debugger should be able to attach to a process under DynamoRIO's control just like it would natively. Previously discussed transparency issues overlap with Debugging Transparency. Stack Transparency and Data Transparency ensure that callstacks and application memory show up correctly. However, DynamoRIO can't entirely hide the fact that the application is running out of a code cache from the debugger. The debugger will see the wrong eip value when breaking in and execution break points will not work correctly (and in fact can lead to corruption of the DynamoRIO code cache). Debugging Tools for Windows and <code>gdb</code> are known to work with DynamoRIO with the exception of the issues noted above.</p>
<h1><a class="anchor" id="sec_trans_alertable"></a>
Alertable System Calls</h1>
<p>On Windows, DynamoRIO does not support a client making alertable system calls. See <a class="el" href="using.html#sec_alertable">Avoid Alertable System Calls</a> for more information. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer" style="float:none;text-align:center"><img border=0 src="favicon.png"> &nbsp;  DynamoRIO API version 5.0.0 --- Wed Sep 10 2014 21:36:44 &nbsp; <img border=0 src="favicon.png">
</small></address>
<!--END !GENERATE_TREEVIEW-->
</body>
</html>
